Developer guide

This section is dedicated mostly for developers who are building clients application to consume live feed provided in ScoutsFeed product.

Before you start receiving data there is a few global conditions to be aware of:

AMQP Service
Our live feed is delivered by AMQP (Advanced Message Queuing Protocol) server.
We can send you examples of simple applications that are able to connect and receive data from our AMQP server. Check details about AMQP Service.
Credentials
You should receive your individual credentials needed to establish connection with our AMQP server.
You will be provided with credentials by our Delivery & Support Team via e-mail.
IP Whitelisting
Our Delivery & Support Team have to add your IP to our whitelist.
For security reason the connection with our AMQP server is possible only from IP addresses existing on our whitelist. Please send us the IP address from where your application will connect to our AMQP server.
Events ordering (booking)
After successfully connecting to the AMQP server your application is ready to receive live data from the games you booked.
You need to order (book) the match from which you want to receive the data.
You can make such an order by logging into our back-office panel or by making an appropriate request to our API. Read more about booking the events.
Live coverage
After ordering the match, you should be able to receive the data in JSON format. Data are sent only if the match is covered by our scout.
Please note:
- data may not arrive if the game is scheduled for the future (scout does not cover the game yet).
- data may not arrive for 5 minutes after order has been made due the CACHE reasons.

If any of the above points is not clear for you, please contact our Delivery & Support Team.

Reason of interruption	Data feed information
The Scout's temporary technical problems	Added “Technical problems” incident (ID:1200) as soon as possible Changed the “betstatus” to “suspended” After restoring the continuity of the data feed, needed correction will be done, the relation will be continued and betstatus will be changed to “active” value If it is not possible to continue the relation - Changed the “scoutsfeed” parameter to “no” which is equivalent to the cessation of data delivery
The Scout lost the transmission source	Added “Technical problems” incident (ID:1200) by Scout Quality Controllers (SQC) as soon as possible Changed the “betstatus” to “suspended” After restoring the continuity of the data feed, needed correction will be done, the relation will be continued and betstatus will be changed to “active” value If it is not possible to continue the relation - Changed the “scoutsfeed” parameter to “no” which is equivalent to the cessation of data delivery
The Scout lost the internet connection	Added “Technical problems” incident (ID:1200) by Scout Quality Controllers (SQC) as soon as possible Changed the “betstatus” to “suspended” After 30 seconds we will stop sending "event_keep_alive" messages After restoring the continuity of the data feed, needed correction will be done, the relation will be continued and betstatus will be changed to “active” value If it is not possible to continue the relation - Changed the “scoutsfeed” parameter to “no” which is equivalent to the cessation of data delivery

URL	https://api.statscore.com/v2/booked-events/
Method	POST
Description	Creates reservations for event for user from token and product.
Authorization required	Yes

.data
message	Response info message.
status	Response code.

Status	Message	Note
200	Successfully reserved event
400	You can order/refuse only events with the status Not started
400	Booking already Exist
400	The selected product is invalid.	When requested product is not valid
403	Invalid credentials. Either the username, password or token you provided is incorrect
404	The requested resource was not found	When requested event does not exist

URL	https://api.statscore.com/v2/booked-events/{event_id}
Method	DELETE
Description	Delete reservations for event in product for user from token
Authorization required	Yes

Status	Message	Note
200	Event successfully removed
400	You can order\refuse only events with the status Not started
400	Booking not Exist
400	The selected product is invalid.	When requested product is not valid
403	Invalid credentials. Either the username, password or token you provided is incorrect
404	The requested resource was not found	When requested event does not exist

Name	Type	Description
client_id	xsd:int	REQUIRED. Assigned to you by the API administrator
product	xsd:string	REQUIRED. Determines product in which given events were booked. Possible values: livescorepro scoutsfeed scoreframe prematchcenter
client_event_id	xsd:string	Determines if clients event identifier is mapped with STATSCORE event. Values could be separated by comma (e.g. 123,234,321). If clients event is not mapped proper message will be returned.
mapped_status	xsd:string	Determines if events are mapped with client_event_id. Possible values: mapped - display events mapped with customer unmapped - display events unmapped with customer all - display all events (mapped and unmapped)
multi_ids	xsd:string	List of events identifiers separated by a comma (e.g. 123,234,321) for which you want to get the events details (Up to 100 ids)
lang	xsd:string	Determines language for the output data
page	xsd:int	Determines offset of paginated data. Default value is 1 which means first page
limit	xsd:int	Determines maximum number of returned records on page. Used in paginated data. Default value is 500. Possible values: 5, 10, 25, 50, 100, 250, 500

URL	https://api.statscore.com/v2/feed
Method	GET
Description	Returns incidents generated by the scouts for all events in the last 24 hours
Cache	0 seconds
Authorization required	Yes

Name	Type	Description
token	xsd:string	REQUIRED. More information concerning authorization in API introduction section
page	xsd:int	Determines offset of paginated data. Default value is 1 which means first page.
limit	xsd:int	Determines maximum number of returned records on page. Used in paginated data. Default value is 50. Possible values: 5, 10, 25, 50, 100, 250, 500
timestamp	xsd:unix_timestamp	Selection date, format UNIX_TIMESTAMP. Only incidents that occurred or were updated after this timestamp will be returned. By default (if no parameter given) incidents from last 24 hours.
timestamp_to	xsd:unix_timestamp	Selection date, format UNIX_TIMESTAMP. Only incidents that occurred before this timestamp will be returned.
important_for_trader	xsd:string	Determines type of incidents (if it's important for trader). By default all types are included. Allowed values: yes - returns only incidents important for trader no - returns only incidents not important for trader
sport_id	xsd:int	Identifier of the sport. Allows incidents for the selected sport to be filtered
type	xsd:string	Determines type of message incident event
incident_ids	xsd:string	List of incidents type identifiers separated by a comma (e.g. 123,234,321) for which you want to get the incident details.
status_id	xsd:int	Determines the event status identifier.

Link	Description
https://api.statscore.com/v2/feed?token={{YOUR_TOKEN}}	Returns all event incidents from the last 24 hours in JSON format
https://api.statscore.com/v2/feed?token={{YOUR_TOKEN}}&sport_id=1	Returns all event incidents from the last 24 hours for basketball events

.feed
id	Unique identifier for the message
uuid	Universally Unique Identifier for the massage. Note: for certain messages, such as updates to a previous, related message, the UUID may be the same. This intentional duplication allows clients to establish correlations between messages, aiding in tracking updates or related data across a system.
type	Possible value: incident event
source	Internal attribute, please dont use this attribute
ut	Information about the date and time of when the message was created. Format UNIX_TIMESTAMP.
..data
...incident	node available only if message type is incident
id	Unique identifier for the incident occurred in the event
action	Describes type of scout operation for the incident. Possible values: insert - new incident generated by the scout update - incident was updated by the scout (e.g. incident "yellow card" is updated when scout fills in the name of the player (participant) delete - incident was deleted (e.g. when the scout adds an incident by mistake, he can delete it)
incident_id	Identifier for the incident
incident_name	Name of the incident. e.g. goal, yellow card, red card etc.
attribute_ids	Attributes identifiers related to incident, separated by a comma (e.g. [397, 398])
confirmation	Describes confirmation status for the incident. Possible values: tbd – appears as default for Goal, Penalty, Red card, Yellow card and Corner incidents. confirmed – appears when the following incident will be confirmed by referee. cancelled – appears when the following incident will be cancelled by referee. Incidents with this value have no effect on statistics.
participant_id	Unique identifier of participant (player, team or coach) name related to incident
participant_name	Participants (player, team or coach) name related to incident.
subparticipant_id	Team id that the player or coach is part of
subparticipant_name	Team name that the player or coach is part of
info	Internal attribute, please dont use this attribute
important_for_trader	Possible values: yes no
important	Internal attribute, please dont use this attribute
add_data	Internal attribute, please dont use this attribute
show_popup	Internal attribute, please dont use this attribute
show_scores	Internal attribute, please dont use this attribute
show_action	Internal attribute, please dont use this attribute
show_time	Internal attribute, please dont use this attribute
show_on_timeline	Internal attribute, please dont use this attribute
event_time	Information when the incident occurs in format MM:SS
event_status_id	Unique identifier of the event status
event_status_name	Name of the event status
period_timer	Informations regarding game clock
direction	Contains information about timer direction. Possible values: down up
time	Time in sync with the game clock
x_pos	Ball position on X axis (percents)
y_pos	Ball position on Y axis (percents)
...event	node available only if message type is event
id	Identifier of the event
action	Describes type of operation for the event. Possible values: insert - new event generated update - event was updated delete - event was deleted
name	The name of the event
start_date	Start date for the event in format: YYYY-MM-DD hh:mm
ft_only	Determines if only the full time result/score of the event is given . Possible values: yes - result/score is updated only when the event is finished no - result/score is updated during the event
coverage_type	Type of event coverage. Possible values: from_venue - means the scout is relaying the event directly from the stadium (max. latency 1 second) from_low_latency_tv - means the scout is relaying the event from tv transmission (max. latency 3 seconds) from_tv - means the scout is relaying the event from tv transmission (max. latency 8 seconds) basic - for this type of coverage we don't provide detailed event incidents (max. latency around 60 seconds)
status_id	Unique identifier of the event status
sport_id	Identifier for the sport in which the event is played
round_id	Unique identifier for the round in which event is played. Possible null value
round_name	Name of the round. Possible null value.
day	Day of the season
neutral_venue	Determines if event is played at a neutral venue. Possible values: yes no
item_status	Describes status for the item (record). Possible values: active - the record is active deleted - the record was deleted by the admin. In the case of when an event was added by mistake
clock_time	Number of seconds that have passed in the current period
clock_status	Clock status. Possible value: running stopped
area_id	Identifier for the area in which the competitions are played
competition_id	Unique identifier for the competition
season_id	Unique identifier for the season.
stage_id	Unique identifier for the stage
tour_id	Unique identifier for the tour in which a competition is played
gender	Competition gender. Possible values: male female mixed
bet_status	Bet status. Possible values: active suspended
bet_cards	Changed when there is a possibility of a card. Possible value: active suspended
bet_corners	Changed when there is a possibility of a corner. Possible value: active suspended
relation_status	Relation status. Attribute for internal purposes. Possible value: not_started - for an event that has not started in_progress - for a live event finished - for an event that has finished 30_min_left - scout confirms his ability to deliver the coverage 30 min before the event 5_min_left - scout confirms his ability to deliver the coverage 5 min before the event
status_type	Type of the status. Possible values: live scheduled finished cancelled interrupted deleted other
scoutsfeed	Information concerning scouts coverage. Possible values: yes - means that play by play incidents will be available for the event no - means that play by play incidents will not be available for the event
latency	Information about the expected latency. Possible values: null (for the event with scoutsfeed=no parameter) 1-2s 3-6s 7-15s
event_stats_level	Internal information, please do not use this field
verified_result	Possible value: yes - result is verified with an official source no - result is not verified with an official source
is_coverage_limited	Determines if event has limited information about players statistics
played_time	Only for soccer. Number of seconds passed in the current period, including additional time
....details
.....detail
id	Unique identifier for the detail. Possible values are different depending on the sport
value	Value related to the detail
....participants
.....participant
counter	Number of participant in the event. Participant with counter="1" is the home team, "2" is the away team
id	Unique identifier of the participant
name	Participants name
short_name	Participants abbreviated name, max length: 20 characters
acronym	Max 3 characters in length mini name, e.g. BAR, REA
area_id	Unique identifier for the area represented by the participant
area_name	Area name represented by the participant
area_code	Max 3 characters in length for the abbreviated area name e.g. GER, POL, FRA
ut	Information about the date and time of when the record was last updated. Format UNIX_TIMESTAMP
......results
.......result
id	Unique identifier for the result. Possible values are different depending on the sport
value	Value related to the results
......stats
.......stat
id	Unique identifier for the statistic. Possible values are different depending on the sport
value	Value related to the statistic
event_status_stats	Sending only with incidents ending the previous part of the game. Contains statistics from previous part of the game
......subparticipants
.......subparticipant
id	Unique identifier of the participant
counter	Number of subparticipant in the event
name	Participants name
short_name	Participants abbreviated name, max length: 20 characters
acronym	Max 3 characters in length mini name, e.g. BAR, REA
area_id	Unique identifier for the area represented by the participant
area_name	Area name represented by the participant
area_code	Max 3 characters in length for the abbreviated area name e.g. GER, POL, FRA
ut	Information about the date and time of when the record was last updated. Format UNIX_TIMESTAMP
........results
.........result
id	Unique identifier for the result
value	Value related to the result
........stats
.........stat
id	Unique identifier for the statistic
value	Value related to the statistic
.........betting
.........bet_statuses
name	Internal information, please do not use this node
value	Internal information, please do not use this node

URL	https://api.statscore.com/v2/feed/{event_id}
Method	GET
Description	Returns all incidents from a single event.
Cache	0 seconds
Authorization required	Yes

URL	https://api.statscore.com/v2/incidents
Method	GET
Description	Returns incidents, which may occur during the event
Cache	60 seconds
Authorization required	Yes

Link	Description
https://api.statscore.com/v2/incidents?token={{YOUR_TOKEN}}	Returns a list of all incidents in JSON format
https://api.statscore.com/v2/incidents?token={{YOUR_TOKEN}}&sport_id=1	Returns a list of incidents which are used in basketball

URL	https://api.statscore.com/v2/logo
Method	GET
Description	Returns a set of logos related to participants
Authorization required	Yes

Link	Description
https://api.statscore.com/v2/logo?token={{YOUR_TOKEN}}	Returns a list of all logos in JSON format
https://api.statscore.com/v2/logo?token={{YOUR_TOKEN}}&ut=1720084284	Returns logos for participants which creation/update date is larger or equal to 04.07.2024 09:11:24 GMT+0000 in JSON format
https://api.statscore.com/v2/logo?token={{YOUR_TOKEN}}&is_national_team=yes	Returns logos for participants which have “is national team” value set to yes in JSON format
https://api.statscore.com/v2/logo?token={{YOUR_TOKEN}}&competition_season_id=60213	Returns logos for participants which were taking part in season 2023 for Africa Cup of Nations in JSON format

Logos
id	Unique identifier for logo
acronym	Short name of participant
logo	Unique URL for logo

URL	https://api.statscore.com/v2/reports/clients-events
Method	GET
Description	Returns raport a list of events booked by the client for the selected product grouped after months.
Cache	900 seconds (15 min.)
Authorization required	Yes

.reports
..report
month	Month of report data
year	Year of report data
tv	The number number of events reserved from tv
venue	The number number of events reserved from venue
auto	The number of events reserved automatically
manual	The number of events reserved manual
total	Total events reserved
ut	Report generate time
..sports
...sport
sport_id	Sport id
count	Items count group by sport

URL	https://api.statscore.com/v2/skins
Method	GET
Description	Returns a set of skins related to participants
Cache	60 seconds
Authorization required	Yes

Link	Description
https://api.statscore.com/v2/skins ?token={{YOUR_TOKEN}}	Returns a list of all skins in JSON format
https://api.statscore.com/v2/skins?token={{YOUR_TOKEN}}&participants_ids=38,42	Returns skins (with patterns ID and colors) for a multiple participants (ID=38 and ID=42) in JSON format

URL	https://api.statscore .com/v2/sports/{sport_id}
Method	GET
Description	Returns information including statuses, result types, details and statistics available for the requested sport
Cache	60 seconds
Authorization required	Yes

URL	https://api.statscore .com/v2/statuses
Method	GET
Description	Returns a list of all available statuses for events from all sports
Cache	60 seconds
Authorization required	Yes

URL	https://api.statscore.com/v2/events/{event_id}/sub-participants
Method	GET
Description	Returns a list of sub-participants for the event
Cache	60 seconds
Authorization required	Yes

.sub_participants
id	Unique identifier of the sub-participant (if the participant exist in the system)
type	Participant type. Possible values: team person
name	Sub-participants name
short_name	Participants' abbreviated name, max length: 20 characters
acronym	Max 3 characters in length mini name, e.g. BAR, REA
gender	Sub-participant gender. Possible value: male female mixed (e.g. for doubles in tennis)
area_id	Unique identifier for the area represented by the sub-participant
area_name	Area name represented by the sub-participant
area_code	Max 3 characters in length for the abbreviated area name e.g. GER, POL, FRA
sport_id	Unique identifier for the sport in which a sub-participant takes part
sport_name	Name of the sport in which a sub-participant takes part
national	Determines if sub-participant is a national team. Possible values: yes no
website	Sub-participants official website
ut	Information about the date and time of when the record was last updated. Format UNIX_TIMESTAMP
old_participant_id	Deprecated. The attribute will be removed in the next API version
slug	Friendly URL for sub-participant
logo	Attribute for internal purposes
virtual	Determines if the participant is a virtual (not real team or player). Possible values: yes no
player_role_importance	Rating of a player’s importance within the team (in this particular season) Possible values: 1 - Fringe player: peripheral, rarely plays, often junior 2 - Backup player: occasional substitute 3 - Rotation player: regularly involved in rotations 4 - Important player: very significant, regular starter 5 - Key player: star of the team, essential to lineup
shirt_nr	Shirt number for the player
details	Detailed data for participant
team_id	Identifier of participant id (team)
lineup_id	Unique identifier of the sub-participant in the event
position	Position's name for selected sub-participant in the event. More detailed than the position_type parameter. Possible values: Soccer goalkeeper 1st lineup bench coach will not play (significant absence) empty Volleyball starting lineup substitute player coach will not play (significant absence) empty Handball goalkeeper player coach will not play (significant absence) empty Futsal goalkeeper starting lineup substitute player coach will not play (significant absence) empty Ice hockey goalkeeper line 1 line 2 line 3 line 4 substitute player coach will not play (significant absence) empty Basketball starting lineup substitute player coach will not play (significant absence) empty Baseball batter pitcher player coach will not play (significant absence) empty Am. football offense defense substitute player coach will not play (significant absence) empty Cricket 1st lineup Substitute coach will not play (significant absence) empty
position_type	Position type of selected position. Recommended for distinguishing starting lineups. Possible values: starting lineup (if the sub-participant is in the starting lineup) substitute (if the sub-participant starts on the bench) coach (if the sub-participant is a coach) will not play (if the sub-participant will not play in this game)
position_reason	Player's general absence reason. Appear only if 'position_type' field is 'will not play'. Possible values: Injury Suspension Other
position_reason_id	Unique identifier of the general reason of absence
position_detailed_reason_name	Player's detailed absence reason. Appear only if 'position_type' field is 'will not play'. Possible values for Injury: Hamstring injury Groin injury Achilles injury Knee injury Head injury Calf injury Thigh injury Chest injury Muscle injury Hip injury Ankle injury Foot injury Back injury Shoulder injury Abdomen injury Collarbone injury Elbow injury Eye injury Fibula injury Forearm injury Hand injury Heel injury Neck injury Olbique injury Quadricep injury Pectoral injury Pelvis injury Shin injury Thumb injury Toe injury Triceps injury Wrist injury Lower leg injury Ribs injury Upper-Body injury Lower-Body injury Patellar tendintis Concussion Illness Physically unable to perform Injured reserve Possible vaulues for Suspension: Cards Team suspension League suspension Federation suspension Possible vaulues for Other: Coach's decision Rest Club decision/contract situation Trade-related reasons Healty scratch International duty Legal issues Military service Unknown reason Administrative reasons Transfer/Club change Personal reasons League investigation Disciplinary action Family emergency Legal matter Bereavement Tactical decision Optioned to minors Not with team G League Concussion protocol Trade pending Health and safety protocols Ineligible to play Return to competition reconditioning
position_detailed_reason_id	Unique identifier of the detailed reason of absence
...stats
id	Unique identifier for the statistic
name	Name of the statistic. Possible values are different depending on the sport
short_name	Abbreviated name of the result.
value	Value related to the statistic
data_type	Defines type of field generated on front (internal purpose only) integer decimal binary_text binary text signed_integer

Statscore ScoutsFeed

Developer Documentation

Table of Contents

Developer guide

AMQP service

Messages types

Message: incident

Message: event

Message: event_keep_alive

Message: events_lineups

Interrupted live data feed delivery

Change of the “scoutsfeed” parameter from “yes” to “no” for live events

Handling key incidents confirmations

Handling incident attributes

API service

Sports data structure

Help & support

API resources

booked-events.create

Resource information

Parameters

Output elements

Possible output messages

Sample curl call

booked-events.delete

Resource information

Method parameters

Parameters

Output elements

Posssible output messages

Sample curl call

events.show

events.index

booked-events.index

[data-colorid=xtoca83dsj]{color:#333333} html[data-color-mode=dark] [data-colorid=xtoca83dsj]{color:#cccccc}Resource information

Method parameters

Query parameters

Method calling examples

Output elements

feed.index

Method parameters

Query parameters

Output elements

feed.show

Method parameters

Query parameters

Output elements

incidents.index

[data-colorid=ftgi1lyjwp]{color:#091e42} html[data-color-mode=dark] [data-colorid=ftgi1lyjwp]{color:#bdd2f6}Resource information

Method parameters

Query parameters

Method calling examples

Output elements

logo.index

Resource information

Method parameters

Query parameters

Method calling examples

Output emelements

reports.clients-events.index

Resource information

Method parameters

Query parameters

Method calling examples

Output elements

skins.index

Method parameters

Method calling examples

Output elements

sports.index

sports.show

Resource information

Method parameters

Query parameters

Method calling examples

Output elements

statuses.index

Resource information

Method parameters

Query parameters

Resource information

Resource information